/**
 * @file kalman_filter.h
 * @brief 单变量卡尔曼滤波器接口头文件
 * @author 废话文学创始人
 * @version 1.1
 * @date 2024-07-14
 * @note 可实现对单变量的动态跟踪和稳定时的滤波
 */

#ifndef __KALMAN_FILTER_H_
#define __KALMAN_FILTER_H_

#include "main.h"

/**
 * @struct Kalman_Estimate
 * @brief 卡尔曼滤波器估计值结构体
 * @details 包含上一次和当前的估计值
 */
typedef struct
{
    float last;    /**< 上一次的估计值 */
    float current; /**< 当前的估计值 */
} Kalman_Estimate;

/**
 * @struct Kalman_Value
 * @brief 卡尔曼滤波器数值结构体
 * @details 包含观测值和估计值
 */
typedef struct
{
    float measure;            /**< 观测值 */
    Kalman_Estimate estimate; /**< 估计值 */
} Kalman_Value;

/**
 * @struct Kalman_Error
 * @brief 卡尔曼滤波器误差结构体
 * @details 包含测量误差和估计误差
 */
typedef struct
{
    float measure;  /**< 测量误差 */
    float estimate; /**< 估计误差 */
} Kalman_Error;

/**
 * @struct Kalman
 * @brief 卡尔曼滤波器主结构体
 * @details 包含滤波器所有的状态和参数
 */
typedef struct
{
    Kalman_Value value;       /**< 数值状态 */
    Kalman_Error error;       /**< 误差参数 */
    float Gain;               /**< 卡尔曼增益系数 */
    float error_estimate_buf; /**< 动态估计误差缓冲区 */
} Kalman;

/**
 * @brief 设置卡尔曼滤波器的误差参数
 * @param[in,out] kalman 卡尔曼滤波器结构体指针
 * @param[in] error_estimate 估计误差
 * @param[in] error_measure 测量误差
 */
void Kalman_Error_Set(Kalman *kalman, float error_estimate, float error_measure);

/**
 * @brief 执行卡尔曼滤波计算
 * @param[in,out] kalman 卡尔曼滤波器结构体指针
 * @param[in] value_measure 测量值输入
 */
void Kalman_calculate(Kalman *kalman, float value_measure);

/**
 * @brief 获取卡尔曼滤波器的当前估计值
 * @param[in] kalman 卡尔曼滤波器结构体
 * @return 当前估计值
 */
float Kalman_Value_Estimate_Get(Kalman kalman);

/**
 * @brief 初始化卡尔曼滤波器
 * @param[in,out] kalman 卡尔曼滤波器结构体指针
 * @param[in] initial_estimate 初始估计值
 * @param[in] error_estimate 初始估计误差
 * @param[in] error_measure 测量误差
 */
void Kalman_Init(Kalman *kalman, float initial_estimate, float error_estimate, float error_measure);

#endif /* __KALMAN_FILTER_H_ */
